deepresearch-flow 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

deepresearch_flow/paper/db.py

@@ -600,6 +600,32 @@ def register_db_commands(db_group: click.Group) -> None:
     )
     @click.option("--cache-dir", "cache_dir", default=None, help="Cache directory for merged inputs")
     @click.option("--no-cache", "no_cache", is_flag=True, help="Disable cache for db serve")
+    @click.option(
+        "--static-base-url",
+        "static_base_url",
+        default=None,
+        help="Static asset base URL (e.g. https://static.example.com)",
+    )
+    @click.option(
+        "--static-mode",
+        "static_mode",
+        type=click.Choice(["auto", "dev", "prod"]),
+        default="auto",
+        show_default=True,
+        help="Static asset mode (dev uses local assets, prod uses static base URL)",
+    )
+    @click.option(
+        "--static-export-dir",
+        "static_export_dir",
+        default=None,
+        help="Optional export directory for hashed static assets",
+    )
+    @click.option(
+        "--pdfjs-cdn-base-url",
+        "pdfjs_cdn_base_url",
+        default=None,
+        help="PDF.js CDN base URL (defaults to jsDelivr)",
+    )
     @click.option("--host", default="127.0.0.1", show_default=True, help="Bind host")
     @click.option("--port", default=8000, type=int, show_default=True, help="Bind port")
     @click.option(
@@ -617,6 +643,10 @@ def register_db_commands(db_group: click.Group) -> None:
         pdf_roots: tuple[str, ...],
         cache_dir: str | None,
         no_cache: bool,
+        static_base_url: str | None,
+        static_mode: str,
+        static_export_dir: str | None,
+        pdfjs_cdn_base_url: str | None,
         host: str,
         port: int,
         fallback_language: str,
@@ -635,6 +665,10 @@ def register_db_commands(db_group: click.Group) -> None:
                 pdf_roots=[Path(root) for root in pdf_roots],
                 cache_dir=Path(cache_dir) if cache_dir else None,
                 use_cache=not no_cache,
+                static_base_url=static_base_url,
+                static_mode=static_mode,
+                static_export_dir=Path(static_export_dir) if static_export_dir else None,
+                pdfjs_cdn_base_url=pdfjs_cdn_base_url,
             )
         except Exception as exc:
             raise click.ClickException(str(exc)) from exc

deepresearch_flow/paper/web/app.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import os
 from pathlib import Path
 
 from starlette.applications import Starlette
@@ -10,8 +11,9 @@ from starlette.routing import Mount, Route
 from starlette.staticfiles import StaticFiles
 
 from deepresearch_flow.paper.db_ops import build_index, load_and_merge_papers
-from deepresearch_flow.paper.web.constants import PDFJS_STATIC_DIR, STATIC_DIR
+from deepresearch_flow.paper.web.constants import DEFAULT_PDFJS_CDN_BASE_URL, PDFJS_STATIC_DIR, STATIC_DIR
 from deepresearch_flow.paper.web.handlers import (
+    api_markdown,
     api_papers,
     api_pdf,
     api_stats,
@@ -21,6 +23,7 @@ from deepresearch_flow.paper.web.handlers import (
     stats_page,
 )
 from deepresearch_flow.paper.web.markdown import create_md_renderer
+from deepresearch_flow.paper.web.static_assets import build_static_assets
 
 logger = logging.getLogger(__name__)
 
@@ -32,6 +35,35 @@ class _NoIndexMiddleware(BaseHTTPMiddleware):
         return response
 
 
+class _StaticAssetFiles(StaticFiles):
+    def __init__(self, *args, cache_control: str | None = None, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._cache_control = cache_control
+
+    async def get_response(self, path: str, scope):  # type: ignore[override]
+        response = await super().get_response(path, scope)
+        if self._cache_control and response.status_code == 200:
+            response.headers.setdefault("Cache-Control", self._cache_control)
+        return response
+
+
+def _normalize_static_mode(value: str | None) -> str:
+    if not value:
+        return "auto"
+    normalized = value.strip().lower()
+    if normalized in {"dev", "development"}:
+        return "dev"
+    if normalized in {"prod", "production"}:
+        return "prod"
+    return "auto"
+
+
+def _resolve_static_mode(value: str, static_base_url: str | None) -> str:
+    if value == "auto":
+        return "prod" if static_base_url else "dev"
+    return value
+
+
 def create_app(
     *,
     db_paths: list[Path],
@@ -42,6 +74,10 @@ def create_app(
     pdf_roots: list[Path] | None = None,
     cache_dir: Path | None = None,
     use_cache: bool = True,
+    static_base_url: str | None = None,
+    static_mode: str | None = None,
+    static_export_dir: Path | None = None,
+    pdfjs_cdn_base_url: str | None = None,
 ) -> Starlette:
     papers = load_and_merge_papers(db_paths, bibtex_path, cache_dir, use_cache, pdf_roots=pdf_roots)
 
@@ -55,6 +91,44 @@ def create_app(
         pdf_roots=pdf_roots,
     )
     md = create_md_renderer()
+    static_base_url = static_base_url or os.getenv("PAPER_DB_STATIC_BASE_URL")
+    static_mode = _normalize_static_mode(static_mode or os.getenv("PAPER_DB_STATIC_MODE"))
+    resolved_mode = _resolve_static_mode(static_mode, static_base_url)
+    export_dir_value = static_export_dir or os.getenv("PAPER_DB_STATIC_EXPORT_DIR")
+    export_dir = Path(export_dir_value) if export_dir_value else None
+    pdfjs_cdn_base_url = (
+        pdfjs_cdn_base_url
+        or os.getenv("PAPER_DB_PDFJS_CDN_BASE_URL")
+        or DEFAULT_PDFJS_CDN_BASE_URL
+    )
+    if pdfjs_cdn_base_url:
+        lowered = pdfjs_cdn_base_url.strip().lower()
+        if lowered in {"none", "off", "local"}:
+            pdfjs_cdn_base_url = None
+        else:
+            pdfjs_cdn_base_url = pdfjs_cdn_base_url.rstrip("/")
+
+    asset_config = None
+    if resolved_mode == "prod":
+        if not static_base_url:
+            logger.warning("Static mode set to prod without base URL; falling back to dev asset routes.")
+            resolved_mode = "dev"
+        else:
+            asset_config = build_static_assets(
+                index,
+                static_base_url=static_base_url,
+                static_export_dir=export_dir,
+            )
+    if resolved_mode == "dev" and export_dir:
+        asset_config = build_static_assets(
+            index,
+            static_base_url="",
+            static_export_dir=export_dir,
+            allow_empty_base=True,
+        )
+    if asset_config is None:
+        asset_config = build_static_assets(index, static_base_url=None)
+
     routes = [
         Route("/", index_page, methods=["GET"]),
         Route("/robots.txt", robots_txt, methods=["GET"]),
@@ -63,6 +137,7 @@ def create_app(
         Route("/api/papers", api_papers, methods=["GET"]),
         Route("/api/stats", api_stats, methods=["GET"]),
         Route("/api/pdf/{source_hash:str}", api_pdf, methods=["GET"]),
+        Route("/api/dev/markdown/{source_hash:str}", api_markdown, methods=["GET"]),
     ]
     if PDFJS_STATIC_DIR.exists():
         routes.append(
@@ -85,10 +160,40 @@ def create_app(
                 name="static",
             )
         )
+    if export_dir and export_dir.exists() and asset_config.enabled and not asset_config.base_url:
+        cache_header = "public, max-age=31536000, immutable"
+        routes.extend(
+            [
+                Mount(
+                    "/pdf",
+                    app=_StaticAssetFiles(directory=str(export_dir / "pdf"), cache_control=cache_header),
+                    name="static_pdf",
+                ),
+                Mount(
+                    "/images",
+                    app=_StaticAssetFiles(directory=str(export_dir / "images"), cache_control=cache_header),
+                    name="static_images",
+                ),
+                Mount(
+                    "/md",
+                    app=_StaticAssetFiles(directory=str(export_dir / "md"), cache_control=cache_header),
+                    name="static_md",
+                ),
+                Mount(
+                    "/md_translate",
+                    app=_StaticAssetFiles(directory=str(export_dir / "md_translate"), cache_control=cache_header),
+                    name="static_md_translate",
+                ),
+            ]
+        )
     app = Starlette(routes=routes)
     app.add_middleware(_NoIndexMiddleware)
     app.state.index = index
     app.state.md = md
     app.state.fallback_language = fallback_language
     app.state.pdf_roots = pdf_roots
+    app.state.static_mode = resolved_mode
+    app.state.asset_config = asset_config
+    app.state.static_export_dir = export_dir
+    app.state.pdfjs_cdn_base_url = pdfjs_cdn_base_url
     return app

deepresearch_flow/paper/web/constants.py

@@ -4,14 +4,15 @@ from pathlib import Path
 
 # CDN URLs for external libraries
 CDN_ECHARTS = "https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"
-CDN_MERMAID = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"
-CDN_KATEX = "https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css"
-CDN_KATEX_JS = "https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.js"
-CDN_KATEX_AUTO = "https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/contrib/auto-render.min.js"
+CDN_MERMAID = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"
+CDN_KATEX = "https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/katex.min.css"
+CDN_KATEX_JS = "https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/katex.min.js"
+CDN_KATEX_AUTO = "https://cdn.jsdelivr.net/npm/katex@0.16.27/dist/contrib/auto-render.min.js"
 
 # Use legacy builds to ensure `pdfjsLib` is available as a global.
 CDN_PDFJS = "https://cdn.jsdelivr.net/npm/pdfjs-dist@3.11.174/legacy/build/pdf.min.js"
 CDN_PDFJS_WORKER = "https://cdn.jsdelivr.net/npm/pdfjs-dist@3.11.174/legacy/build/pdf.worker.min.js"
+DEFAULT_PDFJS_CDN_BASE_URL = "https://cdn.jsdelivr.net/npm/pdfjs-dist@3.11.174"
 
 # PDF.js viewer configuration
 PDFJS_VIEWER_PATH = "/pdfjs/web/viewer.html"

deepresearch_flow/paper/web/handlers/__init__.py

@@ -1,12 +1,13 @@
 """Route handlers for paper web UI."""
 
-from .api import api_papers, api_pdf, api_stats
+from .api import api_markdown, api_papers, api_pdf, api_stats
 from .pages import index_page, paper_detail, robots_txt, stats_page
 
 __all__ = [
     "api_papers",
     "api_pdf",
     "api_stats",
+    "api_markdown",
     "index_page",
     "paper_detail",
     "robots_txt",

deepresearch_flow/paper/web/handlers/api.py

@@ -19,6 +19,8 @@ from deepresearch_flow.paper.web.filters import (
     presence_filter,
     sorted_ids,
 )
+from deepresearch_flow.paper.web.markdown import normalize_markdown_images
+from deepresearch_flow.paper.web.static_assets import resolve_asset_urls
 from deepresearch_flow.paper.web.text import extract_summary_snippet, normalize_title, normalize_venue
 from deepresearch_flow.paper.web.query import Query, QueryTerm, parse_query
 
@@ -92,9 +94,18 @@ def _apply_query(index: PaperIndex, query: Query) -> set[int]:
     return result
 
 
+def _safe_read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="latin-1")
+
+
 async def api_papers(request: Request) -> JSONResponse:
     """API endpoint for paper list with filtering, sorting, and pagination."""
     index: PaperIndex = request.app.state.index
+    asset_config = request.app.state.asset_config
+    prefer_local = request.app.state.static_mode == "dev"
     filters = parse_filters(request)
     page = int(filters["page"])
     page_size = int(filters["page_size"])
@@ -165,6 +176,7 @@ async def api_papers(request: Request) -> JSONResponse:
         source_hash = str(paper.get("source_hash") or stable_hash(str(paper.get("source_path") or idx)))
         translations = index.translated_md_by_hash.get(source_hash, {})
         translation_languages = sorted(translations.keys(), key=str.lower)
+        asset_urls = resolve_asset_urls(index, source_hash, asset_config, prefer_local=prefer_local)
         items.append(
             {
                 "source_hash": source_hash,
@@ -183,6 +195,10 @@ async def api_papers(request: Request) -> JSONResponse:
                 "has_summary": bool(paper.get("_has_summary")),
                 "is_pdf_only": bool(paper.get("_is_pdf_only")),
                 "translation_languages": translation_languages,
+                "pdf_url": asset_urls["pdf_url"],
+                "md_url": asset_urls["md_url"],
+                "md_translated_url": asset_urls["md_translated_url"],
+                "images_base_url": asset_urls["images_base_url"],
             }
         )
 
@@ -215,3 +231,42 @@ async def api_pdf(request: Request) -> Response:
     if allowed_roots and not _ensure_under_roots(pdf_path, allowed_roots):
         return Response("Forbidden", status_code=403)
     return FileResponse(pdf_path)
+
+
+async def api_markdown(request: Request) -> Response:
+    """Dev-only API endpoint to serve raw markdown content."""
+    if request.app.state.static_mode != "dev":
+        return Response("Not Found", status_code=404)
+    index: PaperIndex = request.app.state.index
+    asset_config = request.app.state.asset_config
+    export_dir = request.app.state.static_export_dir
+    source_hash = request.path_params["source_hash"]
+    lang = request.query_params.get("lang")
+    md_path = None
+    if export_dir and asset_config and asset_config.enabled and (asset_config.base_url or "") == "":
+        if lang:
+            translated_url = asset_config.translated_md_urls.get(source_hash, {}).get(lang.lower())
+            if translated_url:
+                rel_path = translated_url.lstrip("/")
+                export_path = export_dir / rel_path
+                if export_path.exists():
+                    raw = _safe_read_text(export_path)
+                    return Response(raw, media_type="text/markdown")
+        else:
+            md_url = asset_config.md_urls.get(source_hash)
+            if md_url:
+                rel_path = md_url.lstrip("/")
+                export_path = export_dir / rel_path
+                if export_path.exists():
+                    raw = _safe_read_text(export_path)
+                    return Response(raw, media_type="text/markdown")
+    if lang:
+        md_path = index.translated_md_by_hash.get(source_hash, {}).get(lang.lower())
+    else:
+        md_path = index.md_path_by_hash.get(source_hash)
+    if not md_path:
+        return Response("Markdown not found", status_code=404)
+    raw = _safe_read_text(md_path)
+    if lang:
+        raw = normalize_markdown_images(raw)
+    return Response(raw, media_type="text/markdown")

deepresearch_flow/paper/web/handlers/pages.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import html
+from pathlib import Path
 from urllib.parse import urlencode
 
 from starlette.requests import Request
@@ -16,6 +17,7 @@ from deepresearch_flow.paper.web.markdown import (
     render_paper_markdown,
     select_template_tag,
 )
+from deepresearch_flow.paper.web.static_assets import resolve_asset_urls
 from deepresearch_flow.paper.web.text import normalize_title
 from deepresearch_flow.paper.web.templates import (
     build_pdfjs_viewer_url,
@@ -23,6 +25,47 @@ from deepresearch_flow.paper.web.templates import (
 )
 
 
+def _safe_read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="latin-1")
+
+
+def _load_markdown_for_view(
+    index: PaperIndex,
+    asset_config,
+    export_dir: Path | None,
+    source_hash: str,
+    *,
+    lang: str | None = None,
+) -> str | None:
+    if export_dir and asset_config and asset_config.enabled and (asset_config.base_url or "") == "":
+        if lang:
+            translated_url = asset_config.translated_md_urls.get(source_hash, {}).get(lang.lower())
+            if translated_url:
+                export_path = export_dir / translated_url.lstrip("/")
+                if export_path.exists():
+                    return _safe_read_text(export_path)
+        else:
+            md_url = asset_config.md_urls.get(source_hash)
+            if md_url:
+                export_path = export_dir / md_url.lstrip("/")
+                if export_path.exists():
+                    return _safe_read_text(export_path)
+
+    if lang:
+        md_path = index.translated_md_by_hash.get(source_hash, {}).get(lang.lower())
+    else:
+        md_path = index.md_path_by_hash.get(source_hash)
+    if not md_path:
+        return None
+    raw = _safe_read_text(md_path)
+    if lang:
+        raw = normalize_markdown_images(raw)
+    return raw
+
+
 async def robots_txt(_: Request) -> Response:
     """Serve robots.txt to disallow all crawlers."""
     return Response("User-agent: *\nDisallow: /\n", media_type="text/plain")
@@ -78,7 +121,13 @@ async def paper_detail(request: Request) -> HTMLResponse:
     embed = request.query_params.get("embed") == "1"
 
     pdf_path = index.pdf_path_by_hash.get(source_hash)
-    pdf_url = f"/api/pdf/{source_hash}"
+    asset_urls = resolve_asset_urls(
+        index,
+        source_hash,
+        request.app.state.asset_config,
+        prefer_local=request.app.state.static_mode == "dev",
+    )
+    pdf_url = asset_urls["pdf_url"] or ""
     source_available = source_hash in index.md_path_by_hash
     translations = index.translated_md_by_hash.get(source_hash, {})
     translation_langs = sorted(translations.keys(), key=str.lower)
@@ -156,14 +205,18 @@ async def paper_detail(request: Request) -> HTMLResponse:
 
     # Initialize template variables
     body_html = ""
-    raw_content = ""
     summary_template_name = ""
     template_warning = ""
     template_controls = ""
     source_path_str = ""
     translated_path_str = ""
+    source_markdown_url = ""
+    translated_markdown_url = ""
+    images_base_url = asset_urls["images_base_url"] or ""
     pdf_filename = ""
     pdfjs_url = ""
+    pdfjs_script_url = ""
+    pdfjs_worker_url = ""
     left_src = ""
     right_src = ""
     split_options: list[tuple[str, str]] = []
@@ -208,21 +261,27 @@ if (templateSelect) {{
 </script>
 """
 
+    prefer_local = request.app.state.static_mode == "dev"
+
     # Source view
     if view == "source":
         source_path = index.md_path_by_hash.get(source_hash)
-        if not source_path:
+        if not source_path or not asset_urls["md_url"]:
             body_html = '<div class="warning">Source markdown not found. Provide --md-root to enable source viewing.</div>'
         else:
-            try:
-                raw = source_path.read_text(encoding="utf-8")
-            except UnicodeDecodeError:
-                raw = source_path.read_text(encoding="latin-1")
-            md_renderer = create_md_renderer()
-            body_html = render_markdown_with_math_placeholders(md_renderer, raw)
-            raw_content = raw
+            source_markdown_url = asset_urls["md_url"] or ""
             source_path_str = str(source_path)
             show_outline = True
+            if prefer_local:
+                raw = _load_markdown_for_view(
+                    index,
+                    request.app.state.asset_config,
+                    request.app.state.static_export_dir,
+                    source_hash,
+                )
+                if raw is not None:
+                    md_renderer = create_md_renderer()
+                    body_html = render_markdown_with_math_placeholders(md_renderer, raw)
 
     # Translated view
     if view == "translated":
@@ -230,38 +289,55 @@ if (templateSelect) {{
             body_html = '<div class="warning">No translated markdown found. Provide <code>--md-translated-root</code> and place <code><base>.<lang>.md</code> under that root.</div>'
         else:
             translated_path = translations.get(selected_lang)
-            if not translated_path:
+            translated_markdown_url = asset_urls["md_translated_url"].get(selected_lang, "")
+            if not translated_path or not translated_markdown_url:
                 body_html = '<div class="warning">Translated markdown not found for the selected language.</div>'
             else:
-                try:
-                    raw = translated_path.read_text(encoding="utf-8")
-                except UnicodeDecodeError:
-                    raw = translated_path.read_text(encoding="latin-1")
-                raw = normalize_markdown_images(raw)
-                md_renderer = create_md_renderer()
-                body_html = render_markdown_with_math_placeholders(md_renderer, raw)
-                raw_content = raw
                 translated_path_str = str(translated_path)
                 show_outline = True
+                if prefer_local:
+                    raw = _load_markdown_for_view(
+                        index,
+                        request.app.state.asset_config,
+                        request.app.state.static_export_dir,
+                        source_hash,
+                        lang=selected_lang,
+                    )
+                    if raw is not None:
+                        md_renderer = create_md_renderer()
+                        body_html = render_markdown_with_math_placeholders(md_renderer, raw)
 
     # PDF view
     if view == "pdf":
-        if not pdf_path:
+        if not pdf_path or not pdf_url:
             body_html = '<div class="warning">PDF not found. Provide --pdf-root to enable PDF viewing.</div>'
         pdf_filename = str(pdf_path.name) if pdf_path else ""
+        pdfjs_cdn_base_url = request.app.state.pdfjs_cdn_base_url
+        if pdfjs_cdn_base_url:
+            pdfjs_script_url = f"{pdfjs_cdn_base_url}/legacy/build/pdf.min.js"
+            pdfjs_worker_url = f"{pdfjs_cdn_base_url}/legacy/build/pdf.worker.min.js"
+        else:
+            pdfjs_script_url = "/pdfjs/build/pdf.js"
+            pdfjs_worker_url = "/pdfjs/build/pdf.worker.js"
 
     # PDF.js view
     if view == "pdfjs":
-        if not pdf_path:
+        if not pdf_path or not pdf_url:
             body_html = '<div class="warning">PDF not found. Provide --pdf-root to enable PDF viewing.</div>'
-        pdfjs_url = build_pdfjs_viewer_url(pdf_url)
+        pdfjs_url = build_pdfjs_viewer_url(
+            pdf_url,
+            cdn_base_url=request.app.state.pdfjs_cdn_base_url,
+        )
         pdf_filename = str(pdf_path.name) if pdf_path else ""
 
     # Split view
     if view == "split":
         def pane_src(pane_view: str) -> str:
-            if pane_view == "pdfjs" and pdf_path:
-                return build_pdfjs_viewer_url(pdf_url)
+            if pane_view == "pdfjs" and pdf_path and pdf_url:
+                return build_pdfjs_viewer_url(
+                    pdf_url,
+                    cdn_base_url=request.app.state.pdfjs_cdn_base_url,
+                )
             params: dict[str, str] = {"view": pane_view, "embed": "1"}
             if pane_view == "summary" and template_param:
                 params["template"] = str(template_param)
@@ -307,12 +383,14 @@ if (templateSelect) {{
             show_outline=show_outline,
             # Content variables
             body_html=body_html,
-            raw_content=raw_content,
             summary_template_name=summary_template_name,
             template_warning=template_warning,
             template_controls=template_controls,
             available_templates=available_templates,
             selected_template_tag=selected_tag,
+            images_base_url=images_base_url,
+            source_markdown_url=source_markdown_url,
+            translated_markdown_url=translated_markdown_url,
             # Source view
             source_path=source_path_str,
             # Translated view
@@ -322,6 +400,8 @@ if (templateSelect) {{
             # PDF view
             pdf_filename=pdf_filename,
             pdf_url=pdf_url,
+            pdfjs_script_url=pdfjs_script_url,
+            pdfjs_worker_url=pdfjs_worker_url,
             # PDF.js view
             pdfjs_url=pdfjs_url,
             # Split view

deepresearch_flow/paper/web/markdown.py

@@ -96,6 +96,64 @@ def normalize_markdown_images(text: str) -> str:
     return "\n".join(out)
 
 
+def normalize_fenced_code_blocks(text: str) -> str:
+    """Ensure fenced code block markers appear on their own lines."""
+    fence_re = re.compile(r"(`{3,}|~{3,})")
+    out: list[str] = []
+    for line in text.splitlines():
+        match = fence_re.search(line)
+        if not match:
+            out.append(line)
+            continue
+        prefix = line[: match.start()]
+        suffix = line[match.start() :]
+        if prefix.strip():
+            out.append(prefix.rstrip())
+            out.append(suffix.lstrip())
+        else:
+            out.append(line)
+    return "\n".join(out)
+
+
+def normalize_unbalanced_fences(text: str) -> str:
+    """Drop unmatched opening fences so later content still renders."""
+    lines = text.splitlines()
+    out: list[str] = []
+    in_fence = False
+    fence_char = ""
+    fence_len = 0
+    fence_open_indices: list[int] = []
+    fence_re = re.compile(r"([`~]{3,})(.*)$")
+
+    for line in lines:
+        stripped = line.lstrip(" ")
+        leading_spaces = len(line) - len(stripped)
+        is_fence = False
+        if leading_spaces <= 3 and stripped:
+            match = fence_re.match(stripped)
+            if match:
+                run = match.group(1)
+                fence = run[0]
+                run_len = len(run)
+                if not in_fence:
+                    in_fence = True
+                    fence_char = fence
+                    fence_len = run_len
+                    fence_open_indices.append(len(out))
+                    is_fence = True
+                elif fence == fence_char and run_len >= fence_len:
+                    in_fence = False
+                    fence_char = ""
+                    fence_len = 0
+                    is_fence = True
+
+        out.append(line)
+
+    if in_fence and fence_open_indices:
+        out.pop(fence_open_indices[-1])
+    return "\n".join(out)
+
+
 def extract_math_placeholders(text: str) -> tuple[str, dict[str, str]]:
     """Extract math expressions and replace with placeholders."""
     placeholders: dict[str, str] = {}
@@ -476,6 +534,8 @@ def extract_html_table_placeholders(text: str) -> tuple[str, dict[str, str]]:
 
 def render_markdown_with_math_placeholders(md: MarkdownIt, text: str) -> str:
     """Render markdown with math, images, and tables properly escaped."""
+    text = normalize_fenced_code_blocks(text)
+    text = normalize_unbalanced_fences(text)
     text = strip_paragraph_wrapped_tables(text)
     text = normalize_footnote_definitions(text)
     rendered, table_placeholders = extract_html_table_placeholders(text)